Defines a pointer to a component callback function. Your component callback function serves as the main entry point into your component and performs the services which your component provides.

typedef ComponentResult(* ComponentRoutineProcPtr) (
    ComponentParameters *cp, 
    Handle componentStorage
);

You would declare your function like this if you were to name it MyComponentRoutineCallback:

ComponentResult MyComponentRoutineCallback (
    ComponentParameters *cp, 
    Handle componentStorage
);

Parameter descriptions

cp

A ComponentParameters structure. The what field of the component parameters structure indicates the action your component should perform. The parameters that the client invoked your function with are contained in the params field of the component parameters structure. Your component can use the CallComponentFunction or CallComponentFunctionWithStorage function to extract the parameters from this structure.

componentStorage

A handle to any memory that your component has associated with the connection. Typically, upon receiving an open request, your component allocates memory and uses the SetComponentInstanceStorage function to associate the allocated memory with the component connection.

function result

Your component should return a value of type ComponentResult. If your component does not return error information as its function result, it should indicate errors using the SetComponentInstanceError function.

DISCUSSION

You pass a pointer to your component callback function to the Component Manager when you register your component. The Component Manager can then call your component when another application or component requests its services. When your component receives a request, it should perform the action specified in the what field of the component parameters structure.

The pointer which you pass to the Component Manager should be a universal procedure pointer (UPP). The definition of the UPP data type for your component function is as follows:

typedef (ComponentRoutineProcPtr) ComponentRoutineUPP;

Before using your component function, you must first create a UPP for your callback function, using the NewComponentRoutineUPP function, as shown here:

ComponentRoutineUPP MyComponentRoutineUPP;

MyComponentRoutineUPP = NewComponentRoutineUPP(&MyComponentRoutineProc);

You then pass MyComponentRoutineUPP to the Component Manager when you register your component. The Component Manager will call your function each time your component receives a request. If you wish to call your component function yourself, you can use the InvokeComponentRoutineUPP function.

result = InvokeComponentRoutineUPP &myParams, myStorage, MyComponentRoutineUPP);

When you are finished with your component callback function, you should dispose of the universal procedure pointer associated with it, using the DisposeComponentRoutineUPP function.

DisposeComponentRoutineUPP(MyComponentRoutineUPP);

To provide a component, you define a component function and supply the appropriate registration information. You store your component function in a code resource and typically store your component’s registration information as resources in a component file.

© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)